/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */

package cgl.granules.dataset;

import java.util.concurrent.ConcurrentHashMap;

import cgl.narada.event.NBEvent;

/**
 * The interface which augments the <code>Dataset</code> interface to support
 * streaming capabilities.
 * 
 * @author Shrideep Pallickara
 * 
 */
public interface StreamingAccess extends Dataset {

	public static final int STRING_SYNOPSIS = 1;
	public int TAG_VALUE_PAIRS = 3;
	public int REG_EXPRESSIONS_SYNOPSIS = 4;
	public static final int HIERARCHICAL_SYNOPSIS = 6;

	/**
	 * Retrieves a portion of the streaming dataset when data is available. This
	 * method will return a NULL if data is not available. In general, this
	 * method should be used in tandem with the DataAvailabilityNotifier.
	 * 
	 * @return A fragment of the streaming dataset
	 * @throws DatasetException
	 *             If there are problems performing the operation
	 */
	public NBEvent getStreamingData() throws DatasetException;

	/**
	 * This method writes data to the output dataset. This method throws an
	 * exception if the Stream producers have not been configured appropriately.
	 * 
	 * @param nbEvent
	 *            The stream fragment that needs to be written
	 * @throws DatasetException
	 *             If there are problems performing the operation
	 */
	public void writeStreamingData(NBEvent nbEvent) throws DatasetException;

	/**
	 * This method writes data to the output dataset. This method throws an
	 * exception if the Stream producers have not been configured appropriately.
	 * 
	 * @param streamInfo
	 *            The stream being written to
	 * @param payload
	 *            The payload for the individual stream fragments
	 * @throws DatasetException
	 *             If there are problems performing the operation
	 */
	public void writeStreamingData(Object streamInfo, byte[] payload)
			throws DatasetException;

	/**
	 * This method writes data to the output dataset. This method throws an
	 * exception if the Stream producers have not been configured appropriately.
	 * 
	 * @param synopsisType
	 *            The synopsis Type for the stream
	 * @param streamInfo
	 *            The stream being written to
	 * @param payload
	 *            The payload for the individual stream fragments
	 * @throws DatasetException
	 *             If there are problems performing the operation
	 */
	public void writeStreamingData(int synopsisType, Object streamInfo,
			byte[] payload) throws DatasetException;

	/**
	 * Add an input stream to this dataset.
	 * 
	 * @param streamSynopsis
	 *            The synopsis of the stream
	 * @param synopsisType
	 *            The type of the stream's synopsis
	 * @return The total number of input streams in this dataset
	 * @throws DatasetException
	 *             If there are problems adding this stream to the set of
	 *             managed streams
	 */
	public int addInputStream(String streamSynopsis, int synopsisType)
			throws DatasetException;

	/**
	 * Removes an input stream from this dataset.
	 * 
	 * @param streamSynopsis
	 *            The synopsis of the stream that will be removed.
	 * @return The total number of input streams that remain in this dataset
	 * @throws DatasetException
	 *             If there are problems removing this stream from the set of
	 *             managed streams
	 */
	public int removeInputStream(String streamSynopsis) throws DatasetException;

	/**
	 * Adds a set of input streams to this dataset.
	 * 
	 * @param streamsToAdd
	 *            The set of streams to be added
	 * @return The total number of input streams in this dataset
	 * @throws DatasetException
	 *             If there are problems adding these streams to the set of
	 *             managed streams
	 * @throws NullPointerException
	 *             If the specified set of streams is NULL.
	 */
	public int addInputStreams(ConcurrentHashMap<String, Integer> streamsToAdd)
			throws DatasetException;

	/**
	 * Removes a set of input streams from this dataset.
	 * 
	 * @param streamsToRemove
	 *            The set of streams to be added
	 * @return The total number of input streams in this dataset
	 * @throws DatasetException
	 *             If there are problems removing these streams to the set of
	 *             managed streams
	 * @throws NullPointerException
	 *             If the specified set of streams is NULL.
	 */

	public int removeInputStreams(
			ConcurrentHashMap<String, Integer> streamsToRemove)
			throws DatasetException;

	/**
	 * Check to see if this dataset has any registered input streams.
	 * 
	 * @return <code>true</code> if this dataset has any registered input
	 *         streams;<code>false</code> otherwise.
	 */
	public boolean hasInputStreams();

	/**
	 * Retrieve the number of input streams in this dataset
	 * 
	 * @return The number of input streams in this dataset
	 */
	public int getNumberOfInputStreams();

	/**
	 * Retrieve a HashMap of the constituent input streams.
	 * 
	 * @return The HashMap of the constituent input streams.
	 */
	public ConcurrentHashMap<String, Integer> getInputStreams();

	/**
	 * Add an output stream to this dataset.
	 * 
	 * @param streamSynopsis
	 *            The synopsis of the stream
	 * @param synopsisType
	 *            The type of the stream's synopsis
	 * @return The total number of output streams in this dataset
	 * @throws DatasetException
	 *             If there are problems adding this stream to the set of
	 *             managed streams
	 */
	public int addOutputStream(String streamSynopsis, int synopsisType)
			throws DatasetException;

	/**
	 * Removes an output stream from this dataset.
	 * 
	 * @param streamSynopsis
	 *            The synopsis of the stream that will be removed.
	 * @return The total number of output streams that remain in this dataset
	 * @throws DatasetException
	 *             If there are problems removing this stream from the set of
	 *             managed streams
	 */
	public int removeOutputStream(String streamSynopsis)
			throws DatasetException;

	/**
	 * Adds a set of output streams to this dataset.
	 * 
	 * @param streamsToAdd
	 *            The set of output streams to be added
	 * @return The total number of output streams in this dataset
	 * @throws DatasetException
	 *             If there are problems adding these streams to the set of
	 *             managed streams
	 * @throws NullPointerException
	 *             If the specified set of streams is NULL.
	 */

	public int addOutputStreams(ConcurrentHashMap<String, Integer> streamsToAdd)
			throws DatasetException;

	/**
	 * Removes a set of output streams from this dataset.
	 * 
	 * @param streamsToRemove
	 *            The set of output streams to be removed
	 * @return The total number of output streams in this dataset
	 * @throws DatasetException
	 *             If there are problems removing these streams from the set of
	 *             managed streams
	 * @throws NullPointerException
	 *             If the specified set of streams is NULL.
	 */
	public int removeOutputStreams(
			ConcurrentHashMap<String, Integer> streamsToRemove)
			throws DatasetException;

	/**
	 * Check to see if this dataset has any registered output streams.
	 * 
	 * @return <code>true</code> if this dataset has any registered output
	 *         streams;<code>false</code> otherwise.
	 */
	public boolean hasOutputStreams();

	/**
	 * Retrieve the number of output streams in this dataset.
	 * 
	 * @return The number of output streams in this dataset.
	 */
	public int getNumberOfOutputStreams();

	/**
	 * Retrieve a HashMap of the constituent output streams.
	 * 
	 * @return The HashMap of the constituent output streams.
	 */
	public ConcurrentHashMap<String, Integer> getOutputStreams();

	/**
	 * Commit any changes that have been made to the set of streams managed by
	 * this dataset. To reflect the changes of adding one or more streams, this
	 * method needs to be invoked. This method does not need to be invoked by
	 * the client that will be deploying an operation.
	 * 
	 * @throws DatasetException
	 */
	public void commitUpdates() throws DatasetException;

}
